Coverage remained the same at 98.752% when pulling f391570 on documentation_cleanup into 4fa182a on master.

Probably to clarify the docs for --keep, --force-renew, --expand and --duplicate, we should write a section explaining what lineages are, which provides a much better backdrop for understanding what those flags do.

It's unclear to me whether the lineage management docs should just live in the RST documentation, or perhaps whether we should create a new "lineages" section of the CLI documentation, and put some explanation of lineages in there.

## Questions
This is a long comment. There's a lot of information I need. Some of them can be answered more or less inline (or by referring to the numbers); some of them will work better as a whiteboard chat; a few are reminders to myself to include things in the docs based on denaje's requests. @SwartzCr I'm mentioning you but feel free to redirect as needed.

1. Are letsencrypt and certbot equivalent (except that cerbot is the preferred term now)?
2. From denaje, is this correct:
3. If your Linux distro's package manager supports letsencrypt, install it from there and use the letsencrypt binary. ( should be certbot binary? )
4. If not, then clone the git repo and use the certbot-auto binary.
5. Seems like we should make it clear what the plugins do--maybe even on the front page where the dropdowns are. Otherwise, people who are using "none of the above" get dumped into a place where they have to figure out what "certonly" means. I'm ruminating on a way to do this without breaking that nice clean interface. Perhaps a link at the bottom that says "My operating system or webserver is not listed" and links to an explanation of certbot-auto, description of the process at a high level, and a list of plugins?
6. From denaje: "What does 'obtain a cert' mean? I think it means that it creates as certificate on the letsencrypt servers after proving domain ownership, downloads it, and saves it to the filesystem ; if so, this could be made clearer. So, these plugins can be used with the 'certonly' command...can they also be used without the 'certonly' command? Why would I use 'certonly' versus leaving it out? There is still no clear explanation of what this does." So...this could go on the new page linked from the front page as described in 3. But I don't know the answers to his questions.
7. We also need to define what the cert installation process does versus what "authenticators" do. Can you provide more detail?
8. We should provide some simple recipes for the certbot and certbot-auto commands. For 80% of cases, I don't want to look at the man page; I just want to know that for my OS and webserver I need to do ./certbot-auto --apache -d example.com -d www.example.com -d other.example.net (or whatever). There's a bit of this info at https://certbot.eff.org/docs/intro.html#how-to-run-the-client but we should re-cast it to be more step-by-step. How do I choose "standalone" vs. "webroot" for example? Also, let's get this out of "Introduction" and put it into the "Getting Certbot" section. That will allow us to resolve ambiguity and redundancy, and structure the information in a way that lets the reader fall through from the dropdowns gracefully if they are not using an OS/webserver combination with a fully capable plugin. To do this, I'll need a whiteboard chat or email exchange with someone who can help me grok the world of certbot-auto. @SwartzCr maybe?
9. It's not immediately clear what is the difference between certbot and certbot-auto, and I can't find a man page for certbot-auto.
10. Let's move https://certbot.eff.org/docs/using.html#command-line-options down to a reference section and use this space for task-oriented docs. Coming in to the docs as someone using j_random_webserver on whatever OS, I don't care about the man page as much as I care about something that says "Do X to get the cert, put it here, test it this way."
11. Note to myself to add a cautionary note (from denaje): you only need to run letsencrypt successfully once. Each time you run it, it will fetch a brand new certificate and place it in your filesystem with a new name, which is probably undesirable. When your cert is about to expire, you should instead use letsencrypt renew. As far as I understand it, letsencrypt keeps track of all your previously successful certs and renews them using the exact same parameters. It also skips renewals that aren't close to expiration yet (unless you specify --force), so this is a good option for adding to a daily cron job.
12. Need to know more about the --standalone and --webroot options for both getting and renewing certs.
13. Need to really understand certonly.
14. Note to myself: add to docs...
    (default) run Obtain & install a cert in your current webserver
    certonly Obtain cert, but do not install it (aka "auth")
    install Install a previously obtained cert in a server
    renew Renew previously obtained certs that are near expiry
    revoke Revoke a previously obtained certificate
    rollback Rollback server configuration changes made during install
    config_changes Show changes made to server config during installation
    plugins Display information about installed plugins
15. Can you verify that these statements from denaje are true:
    If you don't specify a command, then the command is "run".
    "install a cert in your current webserver" implies that it's going to mess with my server's config files, thus defining what "install" means.
    certonly obtains, but does not install. This means that it will authenticate with the letsencrypt server, generate the certificate, and download it to my filesystem, but it will not mess with my webserver's config files. What is the behavior then if I specify certonly with --apache or --nginx? Does that combination of parameters even make sense?
    "run" is the same as "certonly" followed by "install".
16. Note to myself from denaje:
    Explain up front what "commands" are, particularly certonly. Fold in the explanations from the --help output to make it clear what each command does. Make it clearer that commands are different from plugins, and maybe say that using certain plugins together with some commands doesn't make sense (if my understanding is correct).
    Make it clearer what is happening at each stage. When example commands are given, explain why each of the parameters was chosen.
    Reduce the number of places where things are documented. Make it clear which site is the "official" host. The "Getting Started" page could be folded into the official documentation to reduce confusion, and all documentation links on the home page should point to this official place.
    Increase/add links between pages. For example, when discussing plugins and commands on the "Getting Started" page, you could link to the other pages that describe them in more detail.

@pconrad-fb, thanks for your questions; I've tried to answer them below.

Are letsencrypt and certbot equivalent (except that cerbot is the preferred term now)?

The project used to be called letsencrypt but was renamed to certbot. It is the same codebase, but some people will have old packages and/or scripts and/or third-party guides that refer to the old name.

From denaje, is this correct:
If your Linux distro's package manager supports letsencrypt, install it from there and use the letsencrypt binary. ( should be certbot binary? )

Should probably be certbot everywhere, although a small number of OS package managers will also still use the old name.

If not, then clone the git repo and use the certbot-auto binary.

Right.

Seems like we should make it clear what the plugins do--maybe even on the front page where the dropdowns are. Otherwise, people who are using "none of the above" get dumped into a place where they have to figure out what "certonly" means. I'm ruminating on a way to do this without breaking that nice clean interface. Perhaps a link at the bottom that says "My operating system or webserver is not listed" and links to an explanation of certbot-auto, description of the process at a high level, and a list of plugins?

Yeah, something like that might be useful.

From denaje: "What does 'obtain a cert' mean? I think it means that it creates as certificate on the letsencrypt servers after proving domain ownership, downloads it, and saves it to the filesystem ; if so, this could be made clearer. So, these plugins can be used with the 'certonly' command...can they also be used without the 'certonly' command? Why would I use 'certonly' versus leaving it out? There is still no clear explanation of what this does." So...this could go on the new page linked from the front page as described in 3. But I don't know the answers to his questions.

Obtaining a cert means saving it in the filesystem, while installing it means modifying the configuration file of some server application (such as Apache or Nginx, or others) to refer to that certificate and cause it to be used for inbound TLS connections.

Plugins can be used with certonly or with other commands. Some commands don't necessarily need a plugin (an example is register). A command must be used whenever certbot is run (the default command, if none is specified, is run, which attempts both obtaining and installing a cert).

The point of certonly is to obtain a cert without installing it. This is either because ① you don't need or want an installer to be used now, or you're not ready to install the cert, or you don't trust the installer associated with the server you use, or ② you want to renew or replace an individual existing cert that is already installed, or ③ no useful installer is available for you. I can see that one of these things (renewing individual certs) is not exactly like the others, although from our point of view as Certbot developers, they are all analogous because they only authenticate and cause cert issuance in a lineage, without then invoking installation code.

We also need to define what the cert installation process does versus what "authenticators" do. Can you provide more detail?

The authenticators are plugins that are used to prove to the CA that the user is entitled to obtain certs for a particular domain name or domain names because the user controls the name(s) in question. In order to provide this proof, they need to perform some kind of configuration change that is specified by the CA and also visible to the CA (which is called "completing a challenge"). Authenticators know how to perform one or more challenges; the way that they do this varies from authenticator to authenticator and could include things like changing a file on the system, changing a web server configuration file, spawning a temporary web server, giving instructions to a human user about a configuration change that should be made by hand, and (in the future) perhaps uploading a file to a different server or changing entries in a DNS zone. The appropriate authenticator to use depends on how you want to prove control over names, and which ones are practical options depends on the particular system and context (for example, which web server, if any, is already running).

It's not immediately clear what is the difference between certbot and certbot-auto, and I can't find a man page for certbot-auto.

It depends on how you installed it. If you have an operating system package, you have certbot. If you installed it from git, you have certbot-auto. They take the same options and users are always supposed to run the commands using the forms that they have. (Another distinction is that certbot-auto is usually not in your PATH but certbot usually is.)

Need to know more about the --standalone and --webroot options for both getting and renewing certs.

Those are both plugins. The standalone plugin creates its own temporary webserver in order to perform the authentication step (responding to challenges); the webroot plugin instead responds to challenges by writing files into a specified directory (the "webroot") for each domain, so that an existing webserver that's already running on the system will be able to serve those files at the called-for locations when the CA asks for them.

If you're not running a webserver on your system at all, standalone is great because it will make one for you (and shut it down when it's done). If you are already running a webserver, webroot is probably the best choice as long as the webserver is somehow serving files out of the filesystem (as opposed to out of a database or something). An advantage of webroot is that it works without any specific knowledge of webserver integration, so it will work well today with non-Apache webservers as well as Apache (though in that case only with certonly because webroot does not offer an installer!).

Need to really understand certonly.

certonly is named in contrast to the idea of obtaining and installing a cert; it is "cert only" because it only obtains the cert. As I noted above, you can also use it for individual-cert renewals, whether due to expiry or due to a change in the content of the cert, or if you want to change the defaults for how the cert will be renewed in the future (e.g., to change which plugin will be used for renewal). certonly always saves the most recent settings that were used to obtain an individual cert in the renewal configuration file for that lineage.

Can you verify that these statements from denaje are true: If you don't specify a command, then the command is "run".

Yes.

"install a cert in your current webserver" implies that it's going to mess with my server's config files, thus defining what "install" means.

Yes.

certonly obtains, but does not install. This means that it will authenticate with the letsencrypt server, generate the certificate, and download it to my filesystem, but it will not mess with my webserver's config files.

Yes.

What is the behavior then if I specify certonly with --apache or --nginx? Does that combination of parameters even make sense?

Yes, those plugins provide an authenticator which attempts to satisfy challenges by changing web server configurations (what's now called the TLS-SNI-01 challenge method). In that case, the plugin will be used to perform these changes in order to respond to challenges from the CA. This is an alternative to using the webroot plugin in this context. You would need to have the corresponding web server installed and running.

"run" is the same as "certonly" followed by "install".

Yes. (I think there might be some minor details about this, but this is generally the way we think of it.)

I have a couple more questions in return.

1. Do you get certbot-auto (if necessary) by Cloning the git repository
   at https://github.com/certbot/certbot/ or by using
   wget https://dl.eff.org/certbot-auto?
2. What percentage of users will fall through to using certbot-auto and
   not following the automated prompts? That is, what percentage of users will
   specify plugins and other options to get certbot-auto to do specific things?

Thanks,
Peter

If not, then clone the git repo and use the certbot-auto binary.
Right.

and

1. Do you get certbot-auto (if necessary) by Cloning the git repository

I think for most people we'd suggest they get the certbot-auto file from https://dl.eff.org/certbot-auto

1. What percentage of users will fall through to using certbot-auto and not following the automated prompts? That is, what percentage of users will specify plugins and other options to get certbot-auto to do specific things?

Hmm, I'm not sure I think beginner users will go through the graphical prompt and choose apache when prompted, more advanced users might find themselves doing everything via command-line, though I think the install instructions are critical here.

hmm, this never got merged - @schoen do you think this is still needed - would you mind cleaning up the merge conflicts so we can submit it if so?

Coverage increased (+0.0003%) to 98.812% when pulling 65605f7 on documentation_cleanup into 9525fa8 on master.

Coverage remained the same at 98.759% when pulling 0c0603b on documentation_cleanup into 61f3d53 on master.

Coverage remained the same at 98.759% when pulling 0c0603b on documentation_cleanup into 61f3d53 on master.

Coverage remained the same at 98.759% when pulling 44cf404 on documentation_cleanup into 61f3d53 on master.